.TH CLIENTUPDATE 1 "Version 4.3.13:  7 Jan 2014" "Xymon"
.SH NAME
clientupdate \- Xymon client update utility
.SH SYNOPSIS
.B "clientupdate [options]"

.SH DESCRIPTION
\fBclientupdate\fR is part of the Xymon client. It is responsible
for updating an existing client installation from a central
repository of client packages stored on the Xymon server.

When the Xymon client sends a normal client report to the Xymon
server, the server responds with the section of the
.I client-local.cfg(5)
file that is relevant to this client. Included in this may be
a "clientversion" value. The clientversion received from the server
is compared against the current clientversion installed on the client, 
as determined by the contents of the $XYMONHOME/etc/clientversion.cfg
file. If the two versions are not identical, clientupdate is
launched to update the client installation.

.SH OPTIONS
.IP "--level"
Report the current clientversion.

.IP "--update=NEWVERSION"
Attempt to update the client to NEWVERSION by fetching this version
of the client software from the Xymon server.

.IP "--reexec"
Used internally during the update process, see \fBOPERATION\fR below.

.IP "--remove-self"
Used internally during the update process. This option causes
the running clientupdate utility to delete itself - it is used
during the update to purge a temporary copy of the clientupdate
utility that is installed in $XYMONTMP.

.SH USING CLIENTUPDATE IN XYMON
To manage updating clients without having to logon to each server,
you can use the clientupdate utility. This is how you setup the
release of a new client version.

.IP "Create the new client"
Setup the new client $XYMONHOME directory, e.g. by copying an existing
client installation to an empty directory and modifying it for your
needs. It is a good idea to delete all files in the tmp/ and logs/
directories, since there is no need to copy these over to all of
the clients. Pay attention to the etc/ files, and make sure that they
are suitable for the systems where you want to deploy this new client.
You can add files - e.g. extension scripts in the ext/ directory -
but the clientupdate utility cannot delete or rename files.

.IP "Package the client"
When your new client software is ready, create a tar-file of the 
new client. All files in the tar archive must have file names 
relative to the clients' $XYMONHOME (usually, ~xymon/client/).
Save the tar file on the Xymon server in 
~xymon/server/download/somefile.tar.  Don't compress it.
It is recommended that you use some sort of operating-system 
and version-numbering scheme for the filename, but you can choose 
whatever filename suits you - the only requirement is that it must
end with ".tar". The part of the filename preceding ".tar" is
what Xymon will use as the "clientversion" ID.

.IP "Configure which hosts receive the new client"
In the 
.I client-local.cfg(5)
file, you must now setup a \fBclientversion:ID\fR line
where the \fBID\fR matches the filename you used for the
tar-file. So if you have packaged the new client into the
file \fBlinux.v2.tar\fR, then the corresponding 
entry in client-local.cfg would be \fBclientversion:linux.v2\fR.

.IP "Wait for xymond to reload client-local.cfg"
xymond will automatically reload the client-local.cfg file
after at most 10 minutes. If you want to force an immediate
reload, send a SIGHUP signal to the xymond process.

.IP "Wait for the client to update"
The next time the client contacts the Xymon server to
send the client data, it will notice the new clientversion
setting in client-local.cfg, and will run \fBclientupdate\fR
to install the new client software. So when the client runs
the next time, it will use the new client software.

.SH OPERATION
\fBclientupdate\fR runs in two steps:

.IP "Re-exec step"
The first step is when clientupdate is first invoked from the xymonclient.sh 
script with the "--re-exec" option. This step copies the clientupdate
program from $XYMONHOME/bin/ to a temporary file in the $XYMONTMP directory.
This is to avoid conflicts when the update procedure installs a new
version of the clientupdate utility itself. Upon completion of this
step, the clientupdate utility automatically launches the next step
by running the program from the file in $XYMONTMP.

.IP "Update step"
The second step downloads the new client software from the Xymon server.
The new software must be packed into a tar file, which clientupdate then
unpacks into the $XYMONHOME directory.

.SH "ENVIRONMENT VARIABLES"
clientupdate uses several of the standard Xymon environment
variables, including \fBXYMONHOME\fR and \fBXYMONTMP\fR.

.SH "SEE ALSO"
xymon(7), xymon(1), client-local.cfg(5)

